Database & Models

• Migration: alembic/versions/create_wallets_table.py - Creates the wallets table with all required fields. Add extra column billable to provider_key
• Model: app/models/wallet.py - Wallet model with relationship to User
• User relationship: Updated to include wallet relationship
• Provider Key: add extra billable flag

Core Services

• WalletService: app/services/wallet_service.py - Implements all core functions:
  • ensure_wallet() - Creates wallet if doesn't exist
  • precheck() - Checks balance > 0 and not blocked
  • adjust() - Handles deposits/deductions with optimistic locking
  • set_blocked() - Block/unblock accounts
  • get() - Retrieve wallet details

API Integration

• Proxy routes: Added wallet precheck to all API endpoints (/chat/completions, /completions, /images/generations, /images/edits, /embeddings)
• Usage tracker: Integrated automatic balance deduction after API usage calculation
• Wallet routes: Basic endpoints to check balance and status at /v1/wallet/

Webhook Infrastructure

• Stripe webhooks: Added placeholder webhook handlers for:
  • payment_intent.succeeded - For crediting wallet balance
  • payment_intent.payment_failed - For handling failed payments
  • invoice.payment_failed - For blocking accounts on failed subscriptions

Request Flow

1. Precheck: For API request, if the provider is billable, checks balance > 0 AND NOT blocked
2. Processing: Request proceeds if precheck passes
3. Deduction: After completion, usage cost is deducted from wallet balance if provider is billable